home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr49 / 134_01.zip / CORO.NRO < prev    next >
Text File  |  1993-06-12  |  12KB  |  411 lines
  1. .so AN.NRO
  2. .TH C_CALL 3 "Call a coroutine"
  3. .SH NAME
  4. C_CALL -- Call a coroutine.
  5. .SH SYNOPSIS
  6. .bo
  7. int c_call (fcv, passval)
  8. .ti +5
  9. .bo
  10. struct c_fcv *fcv;   /* FCV of target coroutine */
  11. .ti +5
  12. .bo
  13. int passval;         /* Value to pass to target */
  14. .SH DESCRIPTION
  15. .PP
  16. C_CALL transfers control to a destination coroutine, given its FCV address
  17. and a value to pass.  The destination coroutine's state is restored from
  18. its FCV, and the originating coroutine is recorded as the CALLER of the
  19. target coroutine.
  20. .SH EXAMPLES
  21. .bo
  22. reply = c_call (mailman, &message);
  23. .SH "RETURN VALUE"
  24. .PP
  25. The return value is the value given as "passval" to whatever coroutine
  26. primitive (usually C_DETACH) next invokes the originating coroutine.
  27. .SH "SEE ALSO"
  28. c_caller (3),
  29. c_detach (3), 
  30. c_resume (3),
  31. CORODOC.NRO
  32. .bp
  33. .TH C_CALLBY 3 "Change a coroutine's caller"
  34. .SH NAME
  35. C_CALLBY - Change a coroutine's caller
  36. .SH SYNOPSIS
  37. .bo
  38. c_callby (fcv)
  39. .br
  40. .ti +5
  41. .bo
  42. struct c_fcv * fcv;    /* FCV of new caller */
  43. .SH DESCRIPTION
  44. .PP
  45. C_CALLBY changes the "caller" of the current coroutine to some other coroutine.
  46. When a C_DETACH is executed, it will resume the coroutine specified by "fcv",
  47. not the original caller.
  48. .SH "RETURN VALUE"
  49. The return value is unspecified.
  50. .SH "SEE ALSO"
  51. c_call (3),
  52. c_caller (3),
  53. c_detach (3)
  54. .SH NOTES
  55. .PP
  56. C_CALLBY is needed only in a few esoteric applications and should normally
  57. not be used.
  58. .bp
  59. .TH C_CALLER 3 Find calling coroutine
  60. .SH NAME
  61. C_CALLER -- Find the present coroutine's "caller."
  62. .SH SYNOPSIS
  63. .bo
  64. struct c_fcv c_caller ();
  65. .SH DESCRIPTION
  66. .PP
  67. C_CALLER returns the FCV of the current coroutine's "caller," i.e., the
  68. coroutine which would be invoked by a DETACH.  This is normally the
  69. coroutine that most recently did a C_CALL.
  70. .SH "RETURN VALUE"
  71. .PP
  72. The return value is the FCV address of the "caller" coroutine.
  73. .bp
  74. .TH C_CREATE 3 "Create a coroutine"
  75. .SH NAME
  76. C_CREATE -- Create a coroutine
  77. .SH SYNOPSIS
  78. .bo
  79. struct c_fcv * c_create (functp, stack, info)
  80. .br
  81. .ti +5
  82. .bo
  83. int (*functp)();   /* Initial entry of coroutine */
  84. .br
  85. .ti +5
  86. .bo
  87. int stack;         /* Stack size in bytes        */
  88. .br
  89. .ti +5
  90. .bo
  91. int info;          /* User_supplied information  */
  92. .SH DESCRIPTION
  93. .PP
  94. C_CREATE allocates space for a coroutine's FCV, and creates the coroutine.
  95. The coroutine, when activated via C_CALL or C_RESUME, will enter at the
  96. initial entry point (*functp).  The argument to the function will be the
  97. "passval" word given to C_CALL or C_RESUME.
  98. .PP
  99. The "stack" parameter specifies the number of bytes of stack space given to
  100. the target coroutine.  The "info" parameter specifies the user information
  101. word in the coroutine's FCV; this word may be examined by C_GETINFO or
  102. modified by C_SETINFO.
  103. .SH EXAMPLES
  104. .bo
  105. mailman = c_create (&mailmaid, 1500, &mailbag);
  106. .br
  107. .in +20
  108. .ti -3
  109. /* Create a coroutine, "mailman", which has as
  110. its "main program" the function "mailmaid".  Give
  111. it 1500 bytes of stack, and set its "info" word to
  112. the address of "mailbag". */
  113. .in -20
  114. .SH "RETURN VALUE"
  115. .PP
  116. The return value is a pointer to the FCV of the newly-created coroutine.
  117. If the coroutine cannot be created (due to lack of memory), the symbolic
  118. constant ERROR (-1) is returned.
  119. .SH "SEE ALSO"
  120. c_destroy (3),
  121. c_resume (3),
  122. CORODOC.NRO
  123. .bp
  124. .TH C_DESTROY 3 "Destroy a coroutine"
  125. .SH NAME
  126. C_DESTROY -- Destroy a coroutine.
  127. .SH SYNOPSIS
  128. .bo
  129. c_destroy (fcv)
  130. .br
  131. .ti +5
  132. .bo
  133. struct c_fcv * fcv;
  134. .SH DESCRIPTION
  135. .PP
  136. C_DESTROY destroys a coroutine, and reclaims the space allocated for its
  137. stack and FCV.
  138. .SH CAVEATS
  139. .PP
  140. .ul 1
  141. Never
  142. attempt to resume (with C_CALL, C_RESUME, or C_DETACH) a coroutine which
  143. has been destroyed.  The result is disastrous.
  144. .SH "RETURN VALUE"
  145. The return value is unspecified.
  146. .SH "SEE ALSO"
  147. c_create (3)
  148. .SH MISCELLANEOUS
  149. .PP
  150. C_DESTROY is available only if ALLOC_ON has been #define'd in BDSCIO.H.
  151. Otherwise, the "free" function (which C_DESTROY uses to reclaim unused memory)
  152. will not exist.
  153. .bp
  154. .TH C_DETACH 3 "Detach to the 'caller'"
  155. .SH NAME
  156. C_DETACH -- Detach to the "caller" coroutine.
  157. .SH SYNOPSIS
  158. .bo
  159. int c_detach (passval)
  160. .br
  161. .ti +5
  162. .bo
  163. int passval;     /* Value to be returned */
  164. .SH DESCRIPTION
  165. .PP
  166. C_DETACH returns to the caller coroutine (generally the one that most
  167. recently did a C_CALL), preserving the state of the detached one.
  168. The "passval" parameter will be returned as the value of C_CALL.
  169. .SH CAVEATS
  170. It is an error to try to detach the main C program.
  171. .SH "RETURN VALUE"
  172. .PP
  173. The return value is the "passval" parameter of the next C_CALL or C_RESUME
  174. to the coroutine.
  175. .SH "SEE ALSO"
  176. c_call (3),
  177. c_resume (3),
  178. CORODOC.NRO
  179. .SH DIAGNOSTICS
  180. .bo
  181. Attempt to detach a coroutine (FCV=xxxx) which has no caller linkage.
  182. .PP
  183. The main C program or some coroutine simple RESUMEd by it has attempted to
  184. DETACH.  Since the caller cannot be determined, the program aborts.
  185. "xxxx" is the FCV address of the offending coroutine.
  186. .bp
  187. .TH C_GETINFO 3 "Get coroutine info word"
  188. .SH NAME
  189. C_GETINFO -- Get information word of a coroutine.
  190. .SH SYNOPSIS
  191. .bo
  192. int c_getinfo (fcv)
  193. .br
  194. .ti +5
  195. .bo
  196. struct c_fcv * fcv;   /* FCV address of coroutine */
  197. .SH DESCRIPTION
  198. .PP
  199. C_GETINFO returns the user-specified information word for the designated
  200. coroutine.  This word is initialized by C_CREATE, and can be modified by
  201. C_SETINFO.  It is normally a pointer to a static data area for the 
  202. coroutine's use.
  203. .SH EXAMPLES
  204. .bo
  205. mailbag = c_getinfo (c_wmi ());
  206. .SH "RETURN VALUE"
  207. .PP
  208. The return value is whatever was stored in the "info" word by C_CREATE or
  209. C_SETINFO.
  210. .SH "SEE ALSO"
  211. c_create (3),
  212. c_setinfo (3)
  213. .bp
  214. .TH C_PASSER 3 "Find previous coroutine"
  215. .SH NAME
  216. C_PASSER -- Find coroutine that invoked current one.
  217. .SH SYNOPSIS
  218. .bo
  219. struct c_fcv * c_passer ();
  220. .SH DESCRIPTION
  221. .PP
  222. C_PASSER returns the FCV address of the coroutine that most recently
  223. transferred to the current one by any means (C_CALL, C_DETACH, or C_RESUME).
  224. .SH "RETURN VALUE"
  225. .PP
  226. The return value is the FCV address of the "passer" coroutine.
  227. .SH "SEE ALSO"
  228. c_resume (3)
  229. .bp
  230. .TH C_RESUME 3 "Resume another coroutine"
  231. .SH NAME
  232. C_RESUME -- Resume another coroutine.
  233. .SH SYNOPSIS
  234. .bo
  235. int c_resume (fcv, passval);
  236. .br
  237. .ti +5
  238. .bo
  239. struct c_fcv * fcv;  /* FCV address of coroutine */
  240. .br
  241. .ti +5
  242. .bo
  243. int passval;         /* Value to pass            */
  244. .SH DESCRIPTION
  245. .PP
  246. C_RESUME is the basic means of transferring control among coroutines.
  247. It accepts the FCV pointer of the coroutine to resume, and a parameter
  248. which gives the information to pass to it.  This information is returned
  249. as the value of the transfer function (C_CALL, C_DETACH, or C_RESUME) which
  250. last departed from the target coroutine, or as the argument to the "initial
  251. entry" function if the coroutine is being invoked for the first time.
  252. .SH EXAMPLES
  253. .bo
  254. answer = c_resume (oracle, &question);
  255. .SH "RETURN VALUE"
  256. .PP
  257. The return value is the "passval" parameter of the C_RESUME that eventually
  258. returns to the originating coroutine.
  259. .SH "SEE ALSO"
  260. c_create (3), c_destroy (3),
  261. CORODOC.NRO
  262. .bp
  263. .TH C_SETINFO 3 "Change coroutine's 'info'"
  264. .SH NAME
  265. C_SETINFO -- Change the "info" word of a coroutine.
  266. .SH SYNOPSIS
  267. .bo
  268. int c_setinfo (fcv, info)
  269. .br
  270. .ti +5
  271. .bo
  272. struct c_fcv * fcv;   /* FCV of coroutine */
  273. .br
  274. .ti +5
  275. .bo
  276. int info;             /* New "info" word  */
  277. .SH DESCRIPTION
  278. .PP
  279. C_SETINFO changes the "user specified information" word of the designated
  280. coroutine.  This word, initialized by C_CREATE and examined by C_GETINFO,
  281. is generally a pointerto a static storage area for the coroutine.
  282. .SH "RETURN VALUE"
  283. .PP
  284. The "info" parameter is returned unchanged.
  285. .SH "SEE ALSO"
  286. create (3),
  287. getinfo (3)
  288. .bp
  289. .TH C_TYPE 3 "Type of coroutine invocation"
  290. .SH NAME
  291. C_TYPE -- Find out how current coroutine was invoked.
  292. .SH SYNOPSIS
  293. .bo
  294. int c_type ();
  295. .SH DESCRIPTION
  296. .PP
  297. C_TYPE finds out how the current coroutine was most recently invoked, and
  298. returns a value indicating the type of invocation
  299. .SH "RETURN VALUE
  300. .PP
  301. The return value is one of the following symbolic constants (available from
  302. CORO.H):
  303. .sp
  304. CT_UNKNOWN
  305. .PP
  306. The coroutine has never been invoked.  This value is returned if the
  307. main C program calls C_TYPE before it has initiated any other coroutine.
  308. .sp
  309. CT_CALL
  310. .PP
  311. The coroutine was invoked by a C_CALL.
  312. .sp
  313. CT_RESUME
  314. .PP
  315. The coroutine was invoked by a C_RESUME.
  316. .sp
  317. CT_DETACH
  318. .PP
  319. The coroutine was invoked by a C_DETACH.
  320. .sp
  321. CT_FALLOFF
  322. .PP
  323. The coroutine was invoked by the implicit DETACH performed when another
  324. coroutine "fell off the end".
  325. .SH "SEE ALSO"
  326. c_passer (3)
  327. .bp
  328. .TH C_WMI 3 "Find current coroutine"
  329. .SH NAME
  330. C_WMI -- Find current coroutine's FCV.
  331. .SH SYNOPSIS
  332. .bo
  333. struct c_fcv * c_wmi ();
  334. .SH DESCRIPTION
  335. .PP
  336. C_WMI locates the FCV of the coroutine which is currently executing.
  337. .SH "RETURN VALUE"
  338. .PP
  339. The return value is the FCV address of the coroutine currently in execution.
  340. .SH NOTES
  341. .PP
  342. WMI stands, in some obscure fashion, for "Who aM I?"
  343. .bp
  344. .TH CORO.H 7 "Coroutine #include file"
  345. .SH NAME
  346. CORO.H -- #include file for coroutine package.
  347. .SH SYNOPSIS
  348. .bo
  349. #include <coro.h>
  350. .SH DESCRIPTION
  351. .PP
  352. CORO.H contains the definitions of the coroutine FCV structure, the
  353. top few bytes of the stack of a coroutine that is out of execution, and
  354. the values returned by "C_TYPE". 
  355. .SH "SEE ALSO"
  356. CORODOC.NRO
  357. .bp
  358. .TH CORPASS 3 "Internal function"
  359. .SH NAME
  360. CORPASS -- Internal function of the coroutine package.
  361. .SH DESCRIPTION
  362. .PP
  363. CORPASS is an internal utility function, written in assembly language,
  364. which the coroutine package uses to perform the stack manipulations needed
  365. to transfer control among coroutines.  It should not be used directly by
  366. the user.
  367. .SH "SEE ALSO"
  368. .PP
  369. A description of the operations performed by CORPASS on its way from one
  370. coroutine to another is available in CORODOC.NRO.
  371. .bp
  372. .TH CORSTART 3 "Internal function"
  373. .SH NAME
  374. CORSTART -- Internal function of the coroutine package.
  375. .SH DESCRIPTION
  376. .PP
  377. CORSTART is an internal utility function, written in assembly language,
  378. which the coroutine package uses to get a coroutine started.  It must
  379. never be called directly from a C program, since its calling sequence
  380. does not conform to the standards established by the C environment.
  381. .SH "SEE ALSO"
  382. .PP
  383. The coroutine starter and procedure for "falling off the end" of a coroutine
  384. are described in CORODOC.NRO.
  385. .bp
  386. .TH CORWMIP 3 "Internal function"
  387. .SH NAME
  388. CORWMIP -- Internal function of the coroutine package.
  389. .SH DESCRIPTION
  390. .PP
  391. CORWMIP is an internal utility function, written in assembly language,
  392. which returns a pointer to the memory location in which the current
  393. coroutine's FCV address (the value returned by C_WMI) is stored.  It
  394. should normally not be called by the user.
  395. .PP
  396. The main program's FCV, a dummy FCV corresponding to "the operating system",
  397. and the procedure which aborts the program if the main program tries to
  398. do a C_DETACH are also kept in the CORWMIP function.
  399. .SH CAVEATS
  400. .PP
  401. The CORWMIP function will not operate correctly if it is loaded in ROM.
  402. A ROM-able version can be built by moving the data between symbolic locations
  403. "wmiptr" and "mainend" to C.CCC, and defining the symbolic locations in
  404. BDS.LIB.  Since coroutines are generally used for large applications likely
  405. to be loaded in RAM under some operating system, the non-ROM-ability is
  406. not a serious limitation.
  407. DOC.NRO.
  408. .bp
  409. .TH CORWMIP 3 "Internal function"
  410. .SH NAME
  411. CORWMIP -- In